home *** CD-ROM | disk | FTP | other *** search
/ The Atari Compendium / The Atari Compendium (Toad Computers) (1994).iso / files / umich / utils / nroff~yu.zoo / readme < prev    next >
Text File  |  1992-09-11  |  7KB  |  249 lines
  1. nroff 1.2.1/man 3.0.1/manpager 1.44 notes
  2. -----------------------------------------
  3.  
  4. This version of nroff has been ported/compiled with GNU C v1.40 with MiNT
  5. libc at PL 19. It should run under TOS, though I only use MiNT (thanx, eric).
  6. The big advantages are: more portable and much faster than alcyon verison.
  7. nroff is -mshort (16 bit). man and manpager have also been ported to gcc.
  8.  
  9. Files here are:
  10.  
  11.     xnroff.ttp    new version 1.2.1 (text formatter)
  12.     man.ttp        new version 3.0.1 (manual front end)
  13.     manpager.ttp    new version 1.44 (alternate to less(1) that understands
  14.             nroff -T output) NOTE: ONLY WORKS ON MONOCHROME AND
  15.             PROBABLY WON'T WORK WITH TT OR SPECIAL MONITORS (uses
  16.             line A to change fonts)!
  17.  
  18.     tmac.an        new for version 1.2.1 nroff (-man macro package)
  19.     tmac.s        probably older version, what i use (-ms macro package)
  20.  
  21.     man.man        nroff source manpage for man(1)
  22.     man.1        formatted manpage for man(1)
  23.     manpager.man    nroff source manpage for manpager(1)
  24.     manpager.1    formatted manpage for manpager(1)
  25.     nroff.man    nroff source manpage for nroff(1)
  26.     nroff.1        formatted manpage for nroff(1)
  27.     man.ma7        nroff source manpage for man(7)
  28.     man.7        formatted manpage for man(7)
  29.     ms.ma7        nroff source manpage for ms(7)
  30.     ms.7        formatted manpage for ms(7)
  31.  
  32.     changes.121    changes to nroff v1.2.1
  33.     readme        you're looking at it
  34.  
  35. For quick help, execute with "-help" switch:
  36.  
  37.     man -help
  38.     manpager -help
  39.     nroff -help
  40.  
  41. For version info, execute with "-version" switch:
  42.  
  43.     man -version
  44.     manpager -version
  45.     nroff -version
  46.  
  47. nroff now reads from stdin, so you will have to give it a ^C to exit here.
  48.  
  49. To read the formatted manpages after you have unpacked this (and noting
  50. you will need a standard ST with mono monitor to run manpager), do:
  51.  
  52.     manpager nroff.1
  53.     manpager man.1
  54.     manpager manpager.1
  55.     manpager man.7
  56.     manpager ms.7
  57.  
  58. manpager works like less. Exit with "q". manpager can only read one file
  59. at a time (can't do "manpager *.1"). it is usually only invoked by man.
  60.  
  61. See changes.121 file for changes since last rev. Main things are addition
  62. of hyphenation (.nh, .hy but no \% yet) and .tm (write to stderr). Some
  63. bug fixes, too.
  64.  
  65. man has been revamped, but I don't have a changes file. Mostly bugs have
  66. been fixed, port to gcc, and -m/-M change (see below and manpage).
  67.  
  68. manpager is also basically the same. I have added some support specific
  69. to my environment that you will probably never see. For example, manpager
  70. understands _^H sequences (underline). This nroff does not generate these
  71. (unix nroff does). This is automatically detected. I think that was the
  72. only change, other than port to gcc.
  73.  
  74. Note: the biggest problem with this nroff is that the macro package for
  75. man (-man, tmac.an) does NOT have a .TP macro. You will have to convert
  76. manpages that use .TP to instead use .IP:
  77.  
  78.     .TP
  79.     tag
  80.     text...
  81.  
  82. becomes:
  83.  
  84.     .IP "tag"
  85.     text...
  86.  
  87. and
  88.     .TP
  89.     .B tag
  90.     text...
  91.  
  92. becomes:
  93.  
  94.     .IP "\fBtag\fR"
  95.     text...
  96.  
  97. and
  98.  
  99.     .TP 5
  100.     tag
  101.     text...
  102.  
  103. becomes
  104.  
  105.     .IP "tag" 5
  106.     text...
  107.  
  108. The result will be something like:
  109.  
  110.     tag
  111.         text....
  112.  
  113. The tag is always on a seperate line, no matter how short it is.
  114.  
  115. For some reason \fP does not work correctly either, so use \fR instead. I
  116. have formatted literally hundreds of manpages with nroff, and I 95% or any
  117. problems deal with .TP and \fP. Some day I'll add diversions so .TP can
  118. be supported. In the meantime, get out your editor and make these changes.
  119.  
  120. I use MiNT (0.94) and run the tcsh (thanks again, eric!). I have the following
  121. in my tcsh.rc file:
  122.  
  123.     setenv PAGER c:\usr\bin\less.ttp
  124.     setenv MANPAGER d:\usr\ucb\manpager.ttp
  125.     setenv MANDIR d:\usr\man
  126.     setenv MANPATH d:\usr\man
  127.     setenv TMACDIR c:\lib\tmac
  128.     setenv TMPDIR h:\tmp
  129.     setenv TEMP h:\tmp
  130.  
  131. This configures nroff and man:
  132.  
  133.     MANPAGER
  134.     PAGER        man looks first for MANPAGER as the pager. if not
  135.             found, it looks for PAGER. if neither are found,
  136.             it uses an internal default pager.
  137.  
  138.     MANDIR
  139.     MANPATH        man looks for manpage directories rooted in this
  140.             directory. you should create files $MANPATH/man[1-8]
  141.             there and put FORMATTED manpages there (man does
  142.             NOT invoke nroff!)
  143.  
  144.     TMACDIR        nroff looks for files here (ie -man on command line
  145.             has nroff look for file $TMACDIR/tmac.an)
  146.  
  147.     TMPDIR
  148.     TEMP        so far these are not used (but may be in future).
  149.             many other programs do use temp files and this is
  150.             where they go.
  151.  
  152. After you do this, copy tmac.an and tmac.s to $TMACDIR:
  153.  
  154.     cp tmac.* $TMACDIR
  155.  
  156. mkdir $MANPATH/{man1,man2,man3,...,man8} and move FORMATTED manpages
  157. to these directories. A manpage has a name xxx.n where n is one of these
  158. numbers [1-8]:
  159.  
  160.     cp *.1 $MANPATH/man1
  161.     cp *.7 $MANPATH/man7
  162.  
  163. Both man and manpager can handle compressed files, so you can also put
  164. xxx.nz files there:
  165.  
  166.     compress *.1 *.7
  167.     cp *.1z $MANPATH/man1
  168.     cp *.7z $MANPATH/man7
  169.  
  170. Copy the executables to a suitable bin directory, e.g.:
  171.  
  172.     cp *.ttp c:/bin
  173.  
  174. I only format manpages for reading with manpager. hence, I always invoke
  175. nroff with:
  176.  
  177.     nroff -T -man file.man > file.1
  178.  
  179. You may want to make an alias:
  180.  
  181.     alias nroff nroff -T
  182.  
  183. Note that there is a number register in tmac.an (O) to control the printing
  184. of page headers. It is currently set to 1 (meaning do NOT print headers, ie
  185. for online docs). If you want headers, change its value to 0 (zero).
  186.  
  187. nroff's -T switch should always be used to format manpages for manpager.
  188. It causes (hardcoded) escape sequences for font changes to be output (see
  189. manpager docs). This will eventually be replaced with configurable device
  190. support (ie -Tdevice). If you don't specify -T, the default is to use vt52
  191. escapes for fonts (and the special chars \(xx are not supported).
  192.  
  193. Example:
  194.  
  195.     You have a manpage named "cmd.1" from a unix system (in source form).
  196.  
  197.     1) first rename it to avoid confusion. I prefer to call manpage source
  198.        "cmd.man" and formatted manpages "cmd.1". On unix systems, there
  199.        is a separate set of directories to store manpage source files
  200.        ($MANPATH/man[1-8]) and formatted files ($MANPATH/cat[1-8]).
  201.        I don't keep manpage source online.
  202.  
  203.         mv cmd.1 cmd.man
  204.  
  205.     2) format it:
  206.  
  207.         nroff -man -T cmd.man >cmd.1
  208.  
  209.     3) preview it:
  210.  
  211.         man -m . cmd.1
  212.  
  213.     4) store it:
  214.  
  215.         cp cmd.1 $MANPATH/man1
  216.  
  217.     5) view it:
  218.  
  219.         man cmd
  220.  
  221. Man also supports switches to allow you to override the $MANPATH. This is
  222. helpful for previewing newly formatted manpages in the current directory
  223. before they are permanently installed. See -M and -m switches (-M path
  224. specifies alternate $MANPATH, complete with subdirectories; -m path
  225. specifies absolute path where the file is, ie no path/man1/xxx.1).
  226.  
  227. I am not sure of the state of -k and -f support in man(1) (ie reading
  228. a whatis database). I am working on a whatis(1) and apropos(1) anyway.
  229.  
  230. Finally, a word on conventions. The sections of the manual are based on
  231. the unix programmer's manual:
  232.  
  233.     section    directory    description
  234.  
  235.     1    $MANPATH/man1    commands (eg ls(1))
  236.     2    $MANPATH/man2    system calls (eg open(2))
  237.     3    $MANPATH/man3    library routines (eg fopen(3))
  238.     4    $MANPATH/man4    devices/drives/hardware
  239.     5    $MANPATH/man5    special files (eg termcap(5))
  240.     6    $MANPATH/man6    games
  241.     7    $MANPATH/man7    misc
  242.     8    $MANPATH/man8    sys admin tools (eg reboot(8))
  243.  
  244. enjoy...
  245.  
  246. -Bill Rosenkranz
  247. rosenkra@convex.com
  248.  
  249.